/***
 *    This program is free software; you can redistribute it and/or modify
 *    it under the terms of the GNU General Public License as published by
 *    the Free Software Foundation; either version 2 of the License, or
 *    (at your option) any later version.
 *
 *    This program is distributed in the hope that it will be useful,
 *    but WITHOUT ANY WARRANTY; without even the implied warranty of
 *    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *    GNU General Public License for more details.
 *
 *    You should have received a copy of the GNU General Public License
 *    along with this program; if not, write to the Free Software
 *    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 *
 *    Linking this library statically or dynamically with other modules
 *    is making a combined work based on this library. Thus, the terms and
 *    conditions of the GNU General Public License cover the whole
 *    combination.
 *
 *    As a special exception, the copyright holders of this library give
 *    you permission to link this library with independent modules to
 *    produce an executable, regardless of the license terms of these
 *    independent modules, and to copy and distribute the resulting
 *    executable under terms of your choice, provided that you also meet,
 *    for each linked independent module, the terms and conditions of the
 *    license of that module.  An independent module is a module which
 *    is not derived from or based on this library.  If you modify this
 *    library, you may extend this exception to your version of the
 *    library, but you are not obligated to do so.  If you do not wish
 *    to do so, delete this exception statement from your version.
 *
 *    Project: www.simpledbm.org
 *    Author : Dibyendu Majumdar
 *    Email  : d dot majumdar at gmail dot com ignore
 */
package org.simpledbm.network.client.api;

import java.util.Properties;

import org.simpledbm.network.client.impl.SessionManagerImpl;
import org.simpledbm.network.nio.api.Connection;
import org.simpledbm.typesystem.api.RowFactory;
import org.simpledbm.typesystem.api.TableDefinition;
import org.simpledbm.typesystem.api.TypeDescriptor;
import org.simpledbm.typesystem.api.TypeFactory;

/**
 * The SessionManager manages the connection to the SimpleDBM Network Server,
 * and initiates sessions used by the clients. Each SessionManager maintains
 * a single connection to the server. Requests sent over a single connection
 * are serialized.
 * 
 * @author dibyendu majumdar
 */
public abstract class SessionManager {

    /**
     * Obtains an instance of the SessionManager for the specified connection
     * parameters. The client should allow for the fact that the returned
     * instance may be a shared one.
     * 
     * @param properties A set of properties - at present only logging parameters
     *                   are used
     * @param host       The DNS name or IP address of the server
     * @param port       The port the server is listening on
     * @param timeout    The socket timeout in milliseconds. This is the
     *                   timeout for read/write operations.
     * @return A Session Manager object
     */
    public static SessionManager getSessionManager(Properties properties,
            String host, int port, int timeout) {
        return new SessionManagerImpl(properties, host, port, timeout);
    }

    /**
     * Gets the TypeFactory associated with the database.
     * 
     * @return
     */
    public abstract TypeFactory getTypeFactory();

    /**
     * Gets the RowFactory for the database.
     * 
     * @return
     */
    public abstract RowFactory getRowFactory();

    /**
     * Creates a new TableDefinition.
     * 
     * @param name Name of the table's container
     * @param containerId ID of the container; must be unique
     * @param rowType The row definition as an arry of TypeDescriptors
     * @return A TableDefinition object
     */
    public abstract TableDefinition newTableDefinition(String name,
            int containerId, TypeDescriptor[] rowType);

    /**
     * Starts a new session.
     * 
     * @return
     */
    public abstract Session openSession();

    /**
     * Gets the underlying connection object associated with this
     * SessionManager.
     * <p>
     * The connection object must be handled with care, as its correct operation
     * is vital to the client server communication.
     * 
     * @return
     */
    public abstract Connection getConnection();

    /**
     * Closes the SessionManager and its connection with the database,
     * releasing any acquired resources.
     */
    public abstract void close();
}
